FDE W2D5 学习手册 · MCP Server

W2 Day5 · B 级（必须掌握，面试高频）· 4h · 学完能亲手定义一个 MCP Server（医保场景：保单查询/OCR/规则校验 Tool + 文档 Resource + 审核 Prompt）

一、MCP Server 整体结构（医保场景）

一个 MCP Server = 一个进程（stdio）或 HTTP 服务，向 Client 暴露若干 Tools / Resources / Prompts。本日以"特药理赔审核"为例，目标 Server 包含：

二、用 Python SDK 搭 Server 骨架

2.1 选择实现方式

官方 Python SDK 提供高层封装 FastMCP（装饰器式，最常用）和低层 Server（手写 handler）。面试与落地推荐 FastMCP：用 @mcp.tool() / @mcp.resource() / @mcp.prompt() 声明能力，SDK 自动生成 schema 并注册。

2.2 最小骨架

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("insurance-claim-server")  # Server 名（serverInfo）

@mcp.tool()
def query_policy(policy_no: str) -> dict:
    """按保单号查询保单状态、额度、被保人。"""
    # 调内部保单库（此处省略）
    return {"policy_no": policy_no, "status": "active", "limit": 50000}

if __name__ == "__main__":
    mcp.run(transport="stdio")  # 或 transport="streamable-http"

2.3 运行与连接

三、定义第一个 Tool：保单查询（schema + 实现 + 注册）

3.1 三段式

1. schema（输入契约）：由函数签名 + 类型注解 + docstring 生成 inputSchema（参数名、类型、必填、描述）。
2. 实现（业务逻辑）：函数体调内部保单库，返回结构化结果。
3. 注册（暴露给 Client）：@mcp.tool() 装饰即注册，握手后出现在 tools/list。

3.2 完善示例

@mcp.tool()
def query_policy(policy_no: str, fields: list[str] | None = None) -> dict:
    """
    按保单号查询保单信息。
    :param policy_no: 保单号，如 'PA2024-123456'
    :param fields: 可选，指定返回字段；为空返回全部
    :return: 含 status/limit/insured 的字典
    """
    rec = policy_db.get(policy_no)          # 内部查询（医保核心库）
    if not rec:
        return {"found": False, "policy_no": policy_no}
    return {"found": True, **rec}

四、实现 OCR Tool

OCR Tool 把病历/发票图片或 PDF 转成结构化文本，供后续规则校验与生成使用。注意它是有副作用吗——OCR 本身是只读识别（readOnlyHint=true），但可能写临时文件。

@mcp.tool()
def ocr_document(image_path: str) -> dict:
    """
    对病历/发票图片做 OCR，返回结构化文本与关键字段。
    :param image_path: 图片或 PDF 路径
    :return: { text, fields: {patient, hospital, date} }
    """
    text = ocr_engine.recognize(image_path)   # 调用 OCR 引擎
    return {"text": text, "fields": extract_fields(text)}

五、实现特药规则校验 Tool

规则校验 Tool 是"理赔大脑"：输入诊断、药品、既往史，对照特药目录/适应症/医保限制，输出是否可报销及理由。

@mcp.tool()
def check_drug_rule(diagnosis: str, drug_name: str, policy_no: str) -> dict:
    """
    校验某特药是否符合报销规则。
    :param diagnosis: 诊断名称
    :param drug_name: 药品名（如 '奥希美替尼'）
    :param policy_no: 保单号（用于额度关联）
    :return: { covered: bool, reason, max_amount }
    """
    rule = drug_rule_db.lookup(drug_name, diagnosis)   # 特药目录+适应症
    if not rule or not rule.covered:
        return {"covered": False, "reason": "不在适应症范围", "max_amount": 0}
    return {"covered": True, "reason": rule.reason, "max_amount": rule.limit}

六、inputSchema 设计要点

from typing import Literal
@mcp.tool()
def check_drug_rule(diagnosis: str, drug_name: str,
                    region: Literal["北京","上海","全国"] = "全国") -> dict:
    ...

七、定义 Resource：保单文档

Resource 是只读数据/上下文，由应用注入模型上下文，而非模型触发执行。用 @mcp.resource() 声明，URI 作为句柄。

@mcp.resource("policy://{policy_no}/document")
def policy_document(policy_no: str) -> str:
    """返回某保单的原始条款文本（只读上下文）。"""
    return policy_store.load_text(policy_no)

Client/Host 通过 resources/read 按 URI 读取，把文本塞进提示上下文，让模型"看到原文"再做判断（配合引用溯源）。

八、定义 Prompt：理赔审核模板

Prompt 是用户可选的提示词模板，带参数，由用户在 Host 里点选填入。用 @mcp.prompt() 声明。

@mcp.prompt()
def claim_review_prompt(policy_no: str, drug_name: str) -> str:
    """生成标准理赔审核提示词。"""
    return f"""你是特药理赔审核员。请基于保单 {policy_no} 与药品 {drug_name}：
1) 核对诊断与药品适应症；
2) 引用保单条款给出能否报销；
3) 不确定时明确拒答并说明缺什么材料。"""

九、Resource 与 Tool 的分工边界（达标线②）

十、本地调试与 tools/list 验证

10.1 调试步骤

1. 单独跑 Server，确认进程正常启动、无 import 错误。
2. 用 MCP Inspector / SDK 客户端发起 initialize，确认握手成功、版本对齐。
3. 调 tools/list 确认三个 Tool + Resource + Prompt 都在，schema 正确。
4. 用 tools/call 实测参数与返回，检查错误路径（如保单不存在）。

10.2 常见坑

• docstring 缺失 → tools/list 里 description 为空 → 模型不调。
• 返回非 JSON 可序列化 → Client 解析失败。
• 内部异常未捕获 → 整个 call 报错而非结构化返回。

十一、错误处理与可观测

• 结构化错误：返回 {"ok": false, "error": "...", "code": "..."} 而非抛裸异常。
• 超时与降级：内部查询（保单库/OCR）设超时，失败返回降级结果或显式错误。
• 日志与 Trace：记录每次 call 的入参、出参、耗时、错误，便于理赔审计。
• 审计：医保场景 Tool 调用要留痕（谁、查了哪个保单），满足合规。

十二、与 Spring AI（Java）对接：候选人落地路径

候选人是 Java 背景，医保主力后端是 Spring。Spring AI 提供 MCP Server 能力：用 @Tool / ToolCallback 声明工具，框架负责协议层。B站 Spring AI 第 49–56 集 MCP 全套（BV1GfyGBqEm6）讲透 Java 侧实现。

@Tool(description = "按保单号查询保单状态与额度")
public Map<String,Object> queryPolicy(@ToolParam("保单号") String policyNo) {
    return policyService.query(policyNo);   // 复用现有 Java 保单服务
}

十三、面试达标线①：怎么定义一个 MCP Tool

十四、面试达标线②：Resource 与 Tool 的分工

• 判定标准：要"执行动作/产生副作用"→ Tool；只是"把知识放进上下文"→ Resource。
• 触发方不同：Tool 由模型在推理中决定；Resource 由 Host/应用读取注入。
• 医保落点：查保单/OCR/规则校验 = Tool；保单原文/特药目录 = Resource；审核 SOP = Prompt。

十五、W2D5 自测清单

十六、高频面试题速记卡